home *** CD-ROM | disk | FTP | other *** search
/ FishMarket 1.0 / FishMarket v1.0.iso / fishies / 151-175 / disk_166 / stevie / source.doc < prev    next >
C/C++ Source or Header  |  1992-05-06  |  4KB  |  110 lines
  1.  
  2.          Release Notes for STEVIE - Version 3.10a
  3.  
  4.                   Source Notes
  5.  
  6.               Tony Andrews - March 6, 1988
  7.  
  8. Overview
  9. --------
  10.  
  11.     This file provides a brief description of the source code for
  12. Stevie. The data structures are described later as well. For information
  13. specific to porting the editor, see the file 'porting.doc'. This document
  14. is more relevant to people who want to hack on the editor apart from doing
  15. a simple port.
  16.  
  17.     Most of this document was written some time ago so a lot of the
  18. discussion centers on problems related to the Atari ST environment and
  19. compilers. Most of this can be ignored for other systems.
  20.  
  21. Things You Need
  22. ---------------
  23.  
  24.     Stevie has been compiled with both the Alcyon (4.14A) and the
  25. Megamax C compilers. For the posted binary, Megamax was used because
  26. it's less buggy and provides a reasonable malloc(). Ports to other
  27. compilers should be pretty simple. The current ifdef's for ALCYON and
  28. MEGAMAX should point to the potential trouble areas. (See 'porting.doc'
  29. for more information.)
  30.  
  31.     The search code depends on Henry Spencer's regular expression
  32. code. I used a version I got from the net recently (as part of a 'grep'
  33. posting) and had absolutely no trouble compiling it on the ST. Thanks,
  34. Henry!
  35.  
  36.     The file 'getenv.c' contains a getenv routine that may or may
  37. not be needed with your compiler. My version works with Alcyon and
  38. Megamax, under either the Beckemeyer or Gulam shells.
  39.  
  40.     Lastly, you need a decent malloc. Lots of stuff in stevie is
  41. allocated dynamically. The malloc with Alcyon is problematic because
  42. it allocates from the heap between the end of data and the top of stack.
  43. If you make the stack big enough to edit large files, you wind up
  44. wasting space when working with small files. Mallocs that get their memory
  45. from GEMDOS (in fairly large chunks) are much better.
  46.  
  47. Data Structures
  48. ---------------
  49.  
  50.     A brief discussion of the evolution of the data structures will
  51. do much to clarify the code, and explain some of the strangeness you may
  52. see.
  53.  
  54.     In the original version, the file was maintained in memory as a
  55. simple contiguous buffer. References to positions in the file were simply
  56. character pointers. Due to the obvious performance problems inherent in
  57. this approach, I made the following changes.
  58.  
  59.     The file is now represented by a doubly linked list of 'line'
  60. structures defined as follows:
  61.  
  62. struct    line {
  63.     struct    line   *next;    /* next line */
  64.     struct    line   *prev;    /* previous line */
  65.     char           *s;    /* text for this line */
  66.     int            size;    /* actual size of space at 's' */
  67.     unsigned long   num;    /* line "number" */
  68. };
  69.  
  70. The members of the line structure are described more completely here:
  71.  
  72. prev    - pointer to the structure for the prior line, or NULL for the
  73.       first line of the file
  74.  
  75. next    - like 'prev' but points to the next line
  76.  
  77. s    - points to the contents of the line (null terminated)
  78.  
  79. size    - contains the size of the chunk of space pointed to by s. This
  80.       is used so we know when we can add text to a line without getting
  81.       more space. When we DO need more space, we always get a little
  82.       extra so we don't make so many calls to malloc.
  83.  
  84. num    - This is a pseudo line number that makes it easy to compare
  85.       positions within the file. Otherwise, we'd have to traverse
  86.       all the links to tell which line came first.
  87.  
  88.     Since character pointers served to mark file positions in the
  89. original, a similar data object was needed for the new data structures.
  90. This purpose is served by the 'lptr' structure which is defined as:
  91.  
  92. struct    lptr {
  93.     struct    line   *linep;    /* line we're referencing */
  94.     int             index;    /* position within that line */
  95. };
  96.  
  97. The member 'linep' points to the 'line' structure for the line containing
  98. the location of interest. The integer 'index' is the offset into the line
  99. data (member 's') of the character to be referenced.
  100.  
  101. The following typedef's are more commonly used:
  102.  
  103. typedef    struct line    LINE;
  104. typedef    struct lptr    LPTR;
  105.  
  106. Many operations that were trivial with character pointers had to be
  107. implemented by functions or macros to manipulate LPTR's. Most of these are in
  108. the files 'ptrfunc.c' and 'macros.h'. There you'll find functions to increment,
  109. decrement, and compare LPTR's.
  110.